home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 October: Mac OS SDK / Dev.CD Oct 00 SDK1.toast / Development Kits / Mac OS / AIAT / Headers / Storage / IAStorage.h < prev    next >
Encoding:
Text File  |  1998-04-16  |  7.2 KB  |  192 lines  |  [TEXT/CWIE]
  1. // IAStorage.h
  2. //    Copyright:    © 1994 - 1998 by Apple Computer, Inc., all rights reserved.
  3.  
  4.  
  5. // Manages allocation of variable-sized persistent blocks and atomic transactions.
  6.  
  7. #pragma once
  8. #ifndef IAStorage_h
  9. #define IAStorage_h
  10.  
  11. #pragma import on
  12.  
  13. #if PRAGMA_STRUCT_ALIGN
  14.     #pragma options align=power
  15. #endif
  16.  
  17. #include "IAStoreStream.h"
  18.  
  19. #pragma IA_BEGIN_EXPORTS
  20.  
  21. typedef uint32            IABlockID;
  22. typedef uint32            IABlockSize;
  23. typedef uint32            IABlockAddress;
  24.  
  25. //    This interface assumes that block IDs are not raw disk addresses, but rather
  26. //    logical block numbers.  This frees clients from having to shadow blocks
  27. //    changed in a transaction, and also enables compaction without knowledge of
  28. //    client data structures.  The downside is that, to be efficient, the 
  29. //    table mapping block-IDs to block-addresses must be memory-resident.
  30. //    So long as most blocks are reasonably large (around 1kb) the memory
  31. //    requirements should not be too bad.
  32.  
  33. class IAStorage : public IAObject {
  34.     friend class IAOutputBlock;
  35.     friend class IAInputBlock;
  36. public:
  37.     // constructor:        notes storeStream & type, creates mutex
  38.                         IAStorage(IAStoreStream* s, uint32 type);
  39.     // destructor:        deletes storeStream & mutex
  40.                         ~IAStorage();
  41.  
  42.     // Initializes a new storage, or empties an existing one.
  43.     // The storage is left open afterwards.
  44.     virtual void        Initialize() = 0;
  45.  
  46.     // Opens the storage (and its storeStream), enabling subsequent operations.
  47.     // If `writable' is true, destructive operations are supported.
  48.     virtual void        Open(bool writable = false) = 0;
  49.     bool                IsOpen() { return storeStream->IsOpen(); }
  50.     bool                IsWritable() { return storeStream->IsWritable(); }
  51.                 
  52.     // Makes permanent any changes since open.
  53.     virtual void        Commit() = 0;
  54.  
  55.     // Allocates a new block.
  56.     virtual IABlockID    Allocate() = 0;
  57.     
  58.     // Frees a previously allocated block.
  59.     virtual void        Deallocate(IABlockID id) = 0;
  60.     
  61.     // The TOC (table of contents) maintains a list of named block IDs.
  62.     // This enables clients to find their data structures, which may have
  63.     // different block IDs in different storages.
  64.     virtual void        TOC_Set(const char* label, IABlockID id) = 0;
  65.     virtual IABlockID    TOC_Get(const char* label) = 0;
  66.     virtual    bool        TOC_Remove(const char* label) = 0;
  67.     /// Convenient functions capturing common TOC idioms:
  68.     // Adds a new TOC entry whose value is a newly allocated block ID.
  69.     IABlockID            AllocateNamedBlock(const char* name);
  70.     // If an entry already exists, returns it, otherwise calls AllocateNamedBlock().
  71.     IABlockID            GetNamedBlock(const char* name);
  72.     // If an entry exists, remove it.
  73.     bool                RemoveNamedBlock(const char* name);
  74.  
  75.     // The total number of bytes in the storage and free, respectively.
  76.     virtual IABlockSize    TotalSpace() = 0;
  77.     virtual IABlockSize    FreeSpace() = 0;
  78.     
  79.     // Attempts to compact the storage
  80.     virtual void        Compact() = 0;
  81.  
  82.     // in the debug libraries, prints some info about the set to the standard output
  83.     virtual void        PrintFreeList();
  84.     IAStoreStream*        GetStoreStream() const {return storeStream;}
  85.     const uint32        GetStorageType() const {return storageType;}
  86.     IAMutex*            GetMutex() const {return mutex;}
  87.  
  88. protected:
  89.     /// The following called only by InputBlock & OutputBlock (our friends).
  90.     /// Clients should always access block contents through InputBlock & OutputBlock.
  91.     
  92.     // Returns the address that a block may be read from.
  93.     virtual IABlockAddress    GetReadAddress(IABlockID id) = 0;
  94.     
  95.     // Returns the address that a block may be written to.
  96.     virtual IABlockAddress    GetWriteAddress(IABlockID id, IABlockSize size) = 0;
  97.  
  98.     // Returns the number of bytes currently allocated for a block.
  99.     virtual IABlockSize        GetBlockSize(IABlockID id) = 0;
  100.  
  101.     //// Give subclasses direct access to IAStoreStreams.
  102.     void    InitializeSS(IAStoreStream* s)                    { s->Initialize(); }
  103.     void    OpenSS(IAStoreStream* s, bool writeable)        { s->Open(writeable); }
  104.     void    FlushSS(IAStoreStream* s)                        { s->Flush(); }
  105.     uint32    GetEOF(IAStoreStream* s)                        { return s->GetEOF(); }
  106.     void    SetEOF(IAStoreStream* s, uint32 address)        { s->SetEOF(address); }
  107.     void    Write(IAStoreStream* s, uint32 a, const byte* d, uint32 l) { s->Write(a,d,l); }
  108.     uint32    Read(IAStoreStream* s, uint32 a, byte* d,  uint32 l) { return s->Read(a,d,l); }
  109.     uint32    GetPosition(IAStoreStream* s)                    { return s->GetPosition(); }
  110.     void    SetPosition(IAStoreStream* s, uint32 a, uint32 b) { s->SetPosition(a, b); }
  111.     void    WriteByte(IAStoreStream* s, byte b)             { s->WriteByte(b); }
  112.     byte    ReadByte(IAStoreStream* s)                        { return s->ReadByte(); }
  113.     void    WriteUInt32(IAStoreStream* s, uint32 i)         { s->WriteUInt32(i); }
  114.     uint32    ReadUInt32(IAStoreStream* s)                    { return s->ReadUInt32(); }
  115.     void    WriteBytes(IAStoreStream* s, const void* b, uint32 l) { s->WriteBytes(b,l); }
  116.     void    ReadBytes(IAStoreStream* s, void* b,  uint32 l)    { s->ReadBytes(b,l); }
  117.     IAMutex* SSMutex(IAStoreStream* s)                        { return s->mutex; }
  118. private:
  119.                         IAStorage(IAStorage&);    // don't define a copy constructor
  120.     IAStoreStream*        storeStream;            // used for raw i/o
  121.     const uint32        storageType;            // identifies the format used by this storage
  122.     IAMutex*            mutex;                    // to synchronize access
  123. };
  124.  
  125. // This should be used instead of a constructor to make a default-format storage.
  126. IAStorage*        IAMakeStorage(IAStoreStream* storeStream);
  127.  
  128.  
  129. // This class is allocated on the stack, as follows:
  130. //        IAOutputBlock    output(storage, blockID, size);
  131. class IAOutputBlock {
  132. public:
  133.     // locks stream's mutex & positions stream at address for write
  134.     // a cloned IAStoreStream can be supplied to improved threaded throughput
  135.     IAOutputBlock(IAStorage* sto, IABlockID id, IABlockSize sz, IAStoreStream* stream = NULL);
  136.     // flushes changes & unlocks stream's mutex
  137.     ~IAOutputBlock();
  138.  
  139.     void                WriteByte(byte b)                    { stream->WriteByte(b); }
  140.     void                WriteUInt32(uint32 i)                 { stream->WriteUInt32(i); }
  141.     void                WriteBuffer(const void* b, uint32 l){ stream->WriteBytes(b, l); }
  142.  
  143.     uint32                GetPosition()                     { return stream->GetPosition(); }
  144. private:
  145.     IAStoreStream*        stream;
  146.  
  147.     void*                operator new(size_t size);        // stack allocate only
  148.                         IAOutputBlock(IAOutputBlock&);    // don't define copy constructor
  149. };
  150.  
  151. // This class is allocated on the stack, as follows:
  152. //        IAInputBlock    input(storage, blockID);
  153. class IAInputBlock {
  154. public:
  155.     // locks stream's mutex & positions stream at address for read
  156.     // a cloned IAStoreStream can be supplied to improved threaded throughput
  157.     IAInputBlock(IAStorage* sto, IABlockID id, IAStoreStream* stream = NULL);
  158.     // unlocks stream's mutex
  159.     ~IAInputBlock();
  160.  
  161.     byte                ReadByte()                         { return stream->ReadByte(); }
  162.     uint32                ReadUInt32()                    { return stream->ReadUInt32(); }
  163.     void                ReadBuffer(void* b,  uint32 l)    { stream->ReadBytes(b, l); }
  164.  
  165.     uint32                GetPosition()                     { return stream->GetPosition(); }
  166. private:
  167.     IAStoreStream*        stream;
  168.  
  169.     void*                operator new(size_t size);        // stack allocate only
  170.                         IAInputBlock(IAInputBlock&);    // don't define copy constructor
  171. };
  172.  
  173.  
  174. IAExceptionCode                StorageInvalid = 'VSIV';
  175. IAExceptionCode                StorageNotInitialized = 'VSNI';
  176. IAExceptionCode                StorageNotOpen = 'VSNO';
  177. IAExceptionCode                StorageAlreadyOpen = 'VSAO';
  178.  
  179. IAExceptionCode                StorageFull = 'VSDF';
  180. IAExceptionCode                StorageNotWritable = 'VSNW';
  181. IAExceptionCode                StorageBlockIDInvalid = 'VSBI';
  182. IAExceptionCode                StorageBlockNameAllocated = 'VSNT';
  183.  
  184. #pragma IA_END_EXPORTS
  185.  
  186. #if PRAGMA_STRUCT_ALIGN
  187.     #pragma options align=reset
  188. #endif
  189.  
  190. #pragma import reset
  191. #endif
  192.